---
icon: GlobeIcon
---

import { ExampleCode } from '@components/example-code'
import { Steps } from 'nextra/components'

# Next.js I18n

> [!WARNING]
>
> This feature is only available in `nextra-theme-docs`.

Nextra supports
[Next.js Internationalized Routing](https://nextjs.org/docs/advanced-features/i18n-routing)
out of the box. These docs explain how to configure and use it.

<Steps>
## Add i18n config

To add multi-language pages to your Nextra application, you need to config
`i18n` in `next.config.mjs` first:

```js filename="next.config.mjs" {8-11}
import nextra from 'nextra'

const withNextra = nextra({
  // ... other Nextra config options
})

export default withNextra({
  i18n: {
    locales: ['en', 'zh', 'de'],
    defaultLocale: 'en'
  }
})
```

> [!NOTE]
>
> You can use any format of
> [UTS Locale Identifiers](https://www.unicode.org/reports/tr35/tr35-59/tr35.html#Identifiers)
> for defining your locales in the `next.config` file, e.g. language with region
> format `en-US` (English as spoken in the United States).

## Configure the docs theme

Add the `i18n` option to your `theme.config.jsx` to configure the language
dropdown:

```js filename="theme.config.jsx"
i18n: [
  { locale: 'en', name: 'English' },
  { locale: 'zh', name: '中文' },
  { locale: 'de', name: 'Deutsch' },
  { locale: 'ar', name: 'العربية', direction: 'rtl' }
]
```

## Automatically detect and redirect to user-selected language (_optional_)

You can automatically detect the user's preferred language and redirect them to
the corresponding version of the site. To achieve this, create a `middleware.ts`
or `middleware.js` file in the root of your project and export Nextra's
middleware function from `nextra/locales`:

<ExampleCode example="swr-site" filePath="middleware.ts" metadata="{1}" />

> [!WARNING]
>
> This approach will not work for i18n sites that are statically exported with
> `output: 'export'` in `nextConfig`.

## Custom 404 page (_optional_)

You can have a custom `not-found.jsx` with translations for an i18n website that
uses a shared theme layout. For guidance on implementing this, you can check out
the
[SWR i18n example](https://github.com/shuding/nextra/blob/c9d0ffc8687644401412b8adc34af220cccddf82/examples/swr-site/app/%5Blang%5D/not-found.ts).

</Steps>
